# Goal Management Commands

The `/goal` command — a persistent goal-driven loop inspired by Ralph Loop.

Back to: [Command Panel Guide](./09.0.Command%20Panel%20Guide.md)

---

## `/goal`

Persistent goal-driven loop (Ralph Loop).

- **Function**: Bind a verifiable goal to the current session. While the goal is in `pursuing` state, after every AI turn the loop automatically injects a continuation prompt to drive the next iteration — until the model explicitly calls the `goal-update_goal` tool with `achieved` / `unmet`, or the token budget is exhausted.
- **Core ideas**:
  - Write vague requirements as **verifiable contracts** (concrete, testable deliverables)
  - The model must build an audit checklist and inspect real files / outputs / test results; proxy signals (e.g. "tests pass") are NOT proof of completion
  - Only the model can mark the goal as completed (`achieved` / `unmet`); `pause` / `resume` / `clear` / budget adjustments are reserved for the user
- **State machine**:
  - `none -> pursuing` (creation)
  - `pursuing -> {paused | achieved | unmet | budget-limited}`
  - `paused -> pursuing` (resume)
  - `* -> none` (clear)

### Subcommand reference

| Subcommand                     | Description                                                       |
| ------------------------------ | ----------------------------------------------------------------- |
| `/goal <objective>`            | Create and start a new goal                                       |
| `/goal <objective> --budget=N` | Create with a token budget in millions (default 2M)               |
| `/goal` or `/goal status`      | Show the current goal summary                                     |
| `/goal pause`                  | Pause the active goal (stop auto-continuation)                    |
| `/goal resume`                 | Resume a paused goal (immediately triggers one continuation turn) |
| `/goal clear`                  | Clear the active goal                                             |

### Parameters

- **`<objective>`**: Goal description. Write it as a verifiable contract — avoid vague wording.
  - Good: `Refactor src/auth/login.ts to async/await; verify with npm test`
  - Bad: `Improve the repo`
- **`--budget=N`**: Token budget cap in millions of tokens. Accepts `--budget=1.5` or `--budget 1.5`. Defaults to 2 (2,000,000 tokens). When exceeded, the goal moves to `budget-limited` and the model gets one final wrap-up turn.

### Examples

```text
/goal Refactor source/utils/foo.ts to async/await; pass npm test
/goal Add unit tests for parseArgs() in source/utils/commands/goal.ts --budget=1
/goal pause
/goal resume
/goal status
/goal clear
```

### Behavior details

- **Create-and-start**: Creating a goal immediately triggers the first AI turn. The goal summary is shown in the conversation as a command message.
- **Auto continuation**: After each AI turn finishes (unless interrupted by the user), the next turn automatically injects a continuation prompt containing the goal, run count, remaining budget, and audit instructions.
- **Only stop condition**: The model MUST call the `goal-update_goal` MCP tool with `status="achieved"` or `status="unmet"`. Declaring completion only in chat text does NOT stop the loop.
- **Token budget**: Input/output tokens are tracked. When the budget is exhausted, the goal switches to `budget-limited`, and the model receives a single "budget limit reached" wrap-up prompt asking for a progress summary, remaining work, and a clear next step — and explicitly forbidding false completion claims.
- **Pause**: Use `/goal pause` or press `ESC` to pause the current turn. `resume` triggers a continuation immediately.
- **Persistence**: Goal records live at `~/.snow/goals/<projectId>/<sessionId>.json`. Only one active goal per session — if a `pursuing` or `paused` goal already exists, you must `clear` it before creating a new one.

### How the model marks completion

The model submits completion status through the `goal-update_goal` MCP tool. Required fields:

- `status`: `achieved` or `unmet`
- `explanation`: A short evidence-based justification (cite files, command output, test results)

The tool description explicitly says: "Do NOT use `achieved` based on proxy signals alone (e.g. tests pass != objective met)."

### Related files

- `source/utils/commands/goal.ts` — `/goal` command parsing and dispatch
- `source/utils/task/goalManager.ts` — State machine, continuation prompts, token budget
- `source/mcp/goal.ts` — `goal-update_goal` tool implementation